Passing Large Number of Arguments as a Dictionary

Let's take example of plot_bands. It requires 10 arguments and most of them are default, but in order to tweak parameters, you still need to access them. Follow These steps to input arguments easily.
In code cell, write plot_bands? and hit enter. This will give Signature and DocString.
Copy arguments and pass to a dictionary dict(what you copied). In a Jupyter Notebook cell, you can edit it:

arg_dict=dict(
    ax=None,
    kpath=None,
    bands=None,
    showlegend=True,
    E_Fermi=0,
    color1=(1, 0, 0.8),
    style1='solid',
    lw1=0.7,
    )
arg_dict

{'ax': None,
 'kpath': None,
 'bands': None,
 'showlegend': True,
 'E_Fermi': 0,
 'color1': (1, 0, 0.8),
 'style1': 'solid',
 'lw1': 0.7}

As you can see, I deleted few unnecessary arguments. Now you can use dictionary unpacking operator ** inside function, it will pass all arguments present in dictionary. Make sure you do not change name of variables, although you can delete as few of them.
Usage: Call function as plot_bands(**arg_dict). You can edit dictionary on fly, or can save it to a file to read (Not recommended, could be a threat to your system security as reading dictionaries from a file could run potentially harmful commands as well.)

Simple Band Struture Plots

Working in object-oriented way, we can have plenty of options in matplotlib. See the example below, which provides an overview of flexibility of matplotlib. All functions are defined in object-oriented way for better compatibility and flexibility.

Example: Graphene

import pivotpy.vr_parser as vp
vr1=vp.export_vasprun(path=f1)
vr2=vp.export_vasprun(path=f2)
import pivotpy.s_plots as sp
import matplotlib.pyplot as plt

fig,ax=plt.subplots(1,3,figsize=(10.2,2.6),sharey=True)
ax0=sp.plot_bands(ax=ax[0],kpath=vr2.kpath,bands=vr2.bands,showlegend=True)

ax1=sp.plot_bands(ax=ax[1],kpath=vr1.kpath,bands=vr1.bands,color1='y')

ax2=sp.plot_bands(ax=ax[2],kpath=vr1.kpath,bands=vr1.bands,color1='y')
ax2=sp.plot_bands(ax=ax[2],kpath=vr2.kpath,bands=vr2.bands,showlegend=True)
xticks=[vr1.kpath[i] for i in [0,30,60,-1]]
txts=["Polarized","Unpolarized","Comparison"]
for axes,txt in zip(ax,txts):
    if axes==ax0:
        sp.modify_axes(ax=axes,ylabel='Energy (eV)')
    sp.modify_axes(ax=axes,ylim=[-10,10],xlim=[xticks[0],xticks[-1]],xticks=xticks,xt_labels=[r'$\Gamma$','M','K',r'$\Gamma$'])
    axes.text(0.05,0.9,txt,bbox=dict(edgecolor='white',facecolor='white', alpha=0.9),transform=axes.transAxes,color='red')
plt.subplots_adjust(hspace=0.01,wspace=0.05)

Below is example where you can add multiple text entries on a quick_bplot.

ax=sp.quick_bplot(path_evr=f2,elim=[-5,5],xt_indices=[0,30,60,-1],xt_labels=['W','K',''],txt='Graphene',ctxt='r')
sp.add_text(ax=ax,xs=[0.35,0.5],ys=[0.55,0.7],txts=[r'$E_{gap}$ = 0 eV','edge states'],colors=['red','blue'])

import pivotpy.s_plots as sp
import matplotlib.pyplot as plt 
plt.style.use('default')
fig,ax=plt.subplots(1,2,figsize=(9,1))
add_colorbar(ax[0],'RGB',vertical=True,N=7)
add_colorbar(ax=ax[1],cmap_or_clist=['r','g','b',2],N=21)

Invalid RGBA argument: 2 
Falling back to default color map!

color_wheel(xy=(0.5,0.5),scale=0.5,color_map='hsv',ticks=[0,1/3,2/3],labels=['Red','Green','Blue'])

<matplotlib.projections.polar.PolarAxes at 0x19ee2822c88>

Including Atomic and Orbital Projections

We can use plot_collection together with arguments of get_pros_data,make_line_collection, see below.

import time
start=time.time()
import numpy as np 
import pivotpy as pp
vr = pp.export_vasprun('E:/Research/graphene_example/ISPIN_2/bands/vasprun.xml',elim=[-10,10])
k=vr.kpath
ef=vr.tdos.E_Fermi
en=vr.bands.evals.SpinUp-ef
pros=vr.pro_bands.pros.SpinUp
gpd_args = dict(kpath=k,evals_set=en,pros_set=pros,scale_data=True)
mlc_args = dict(max_width = 2.5,colors_list = None,rgb = False,uni_width = False, scale_color = False)

Loading from PowerShell Exported Data...

import pivotpy.s_plots as sp 
import matplotlib.pyplot as plt 
plt.style.use('seaborn')
axs = sp.init_figure(ncols=3,figsize=(8,2.6),sharey=True)
axc = axs[0].get_figure().add_axes([0.5,1,0.3,0.04])

gpd_args.update(elements=[[0,1],[0,1],[0,1]],orbs=[[0],[2],[1,3]])
mlc_args['colors_list'] = [(1,0,0,1),(0,1,0,1),(0,0,1,0.4)]
plot_collection(gpd_args,mlc_args,axes=axs[0])
sp.add_legend(ax=axs[0],labels=['C-s','C-pz','C-px+py'],widths=2.5,colors=mlc_args['colors_list'])

gpd_args['orbs'] = [[0],[1,2,3],[4,5,6,7,8]]
plot_collection(gpd_args,mlc_args,axes=axs[1])

mlc_args['uni_width'] = True
plot_collection(gpd_args,mlc_args,axes=axs[2])

_ = [sp.modify_axes(ax=ax) for ax in axs]
sp.add_colorbar(ax=axc,cmap_or_clist = mlc_args['colors_list'],ticklabels=['C-s','C-p','C-d'],ticks=[0,0.5,1])
plt.subplots_adjust(wspace=0.05)
txts=['Default/s,pz,px+py','uni_width=False/s,p,d','uni_width=True/s,p,d']
_ = [sp.add_text(ax=ax,txts=txt) for ax,txt in zip(axs,txts)]
print('Executed in {} seconds.'.format(time.time()-start))

Executed in 1.673912525177002 seconds.

Based on get_pros_data,make_line_collection and plot_collection, below are two functions quick_rgb_lines and quick_color_lines,which can be used without any hassel of changing and passing dictionary of arguments from one function to other. The difference between two is that quick_rgb_lines works with three elemenents only and generates a single variable color and variable thickness line, while quick_color_lines plots single colored as many lines as len(elements) with variable thickness.

quick_rgb_lines() is waraper around make_line_collection(rgb=True). You can pass lists for orbs,labels, and elements each of length 3 which will be plotted on one axes.
- If you do not provide any arguemnts, this will create graph of s orbital of first ion.
- elements argument is special, you can pass index of element which will pick all ions of that type, or list(length=3) of indices of ions, e.g in elements=[0,[0,1],2] of system Ga32As31Bi1, 0 and 2 pick all ions of Ga and Bi respectively, while [0,1] will pick first two ions of Ga.
- If scale_color=True, ecah point on plot is scaled to maximum color, if False, whole data is normalized if scale_data=True.
- color_matrix is to convert between color spaces and play around as you can. Sum of each row up yo 3 columns should be less than or equal to 1. 4th column of color_matrix is for saturation, contrast and brightness from top to bottom in order. Only works if scale_color=True. {% include tip.html content='pivotpy.color_matrix and pivotpy.gray_matrix are 3x4 quick matrices.' %}{% include tip.html content='Use RGB_m for DOS and RGB_f for bands plotting in same color. RGB_f is auto-picked by add_colorbar.' %}

import os
import numpy as np
os.chdir('E:/Research/graphene_example/ISPIN_2/bands')
import matplotlib.pyplot as plt
plt.style.use('ggplot')
import pivotpy as pp
evr = pp.export_vasprun()
args_dict = dict(path_evr=evr,elements=[0,[0,1],[0,1]],orbs=[0,[1],[2,3]],labels=['s','p$_z$','p$_x$+p$_y$'])

axs=pp.init_figure(nrows=2,ncols=3,figsize=(9,5),sharex=True,sharey=True);
caxs = pp.init_figure(nrows=2,ncols=3,figsize=(9,1),sharex=True,sharey=True,top=0.5)
quick_rgb_lines(ax=axs[0,0],**args_dict,spin='up',txt='scale_color=False',scale_color=False)
pp.add_colorbar(caxs[0,0])
quick_rgb_lines(ax=axs[0,1],**args_dict,scale_data=False,scale_color=False,spin='down',txt='scale_[color,data]=False')
pp.add_colorbar(caxs[0,1])
quick_rgb_lines(ax=axs[0,2],**args_dict,spin='both',txt='scale_color=True')
pp.add_colorbar(caxs[0,2])

plt.style.use(['default','seaborn'])
_ = quick_rgb_lines(ax=axs[1,0],**args_dict,spin='up',txt='color_matrix',color_matrix=pp.color_matrix)
pp.add_colorbar(caxs[1,0])
_ = quick_rgb_lines(ax=axs[1,1],**args_dict,spin='down',txt='color_matrix.T',color_matrix=pp.color_matrix.T)
pp.add_colorbar(caxs[1,1])
_ = quick_rgb_lines(ax=axs[1,2],**args_dict,spin='both',txt='gray_matrix',color_matrix=pp.gray_matrix)
pp.add_colorbar(caxs[1,2])
caxs[0,0].get_figure().suptitle("These colorbars are dynamically generated in sequence to above figure's axes")

Loading from PowerShell Exported Data...
 elements[0] = 0 is converted to range(0, 2) which picks all ions of 'C'.To just pick one ion at this index, wrap it in brackets [].

Text(0.5, 0.98, "These colorbars are dynamically generated in sequence to above figure's axes")

quick_color_lines() is waraper around make_line_collection(rgb=False,uni_width=False,scale_color = False). You can pass equal length lists for orbs,labels, and elements either with one axis or mutltiple axes of same length as orbs.
- If you do not provide any arguemnts, this will plots-orbital of first ion.
- elements argument is special, you can pass index of element which will pick all ions of that type, or list of indices of ions, e.g in elements=[0,[0,1],2] of system Ga32As31Bi1, 0 and 2 pick all ions of Ga and Bi respectively, while [0,1] will pick first two ions of Ga.
- If your given len(axis)=1, all projections are plotted on single axis and you can tweak plot aesthetics, legend display etc. There are plenty of options.
- If a label is empty i.e. '', it will not show up in legend.

Colors Selection

Instead of giving custom colors, you can use matplotlib's colormaps to be consistent. Use

plt.colormaps()

to see list of available color maps. To get a color array from a map, you can do the following:

from matplotlib.pyplot import cm
colors  = cm.hsv(np.linspace(0,1,3))
# This will give you three colors from 'hsv' map.

Note: A custom colormaps RGB is registered in session when you import pivotpy, which could be used when plotting DOS with bands of same color. An additional colormap RGB_m a at any moment would represent the latest quick_rgb_lines run.

import os
path='E:/Research/graphene_example/ISPIN_2/bands'
os.chdir(path)
import pivotpy 
import importlib as imp
pp = imp.reload(pivotpy)
import matplotlib.pyplot as plt
axs=pp.init_figure(nrows=1,ncols=3,figsize=(7,2.5),sharey=True,sharex=True)
args_dict=dict(elements=[0,0,[0,1]],orbs=[0,1,[2]],labels=['','$p_z$','$p_x$'],hspace=0.1,wspace=0.07,showlegend=True)
quick_color_lines(axes=axs[0],**args_dict,left=0.06,color_map='flag',spin='up');
quick_color_lines(axes=axs[1],**args_dict,left=0.06,color_map='FCC',spin='down',scale_data=True);
quick_color_lines(axes=axs[2],**args_dict,left=0.06,color_map='RGB',spin='both');

Loading from PowerShell Exported Data...
 elements[0] = 0 is converted to range(0, 2) which picks all ions of 'C'.To just pick one ion at this index, wrap it in brackets [].
 elements[1] = 0 is converted to range(0, 2) which picks all ions of 'C'.To just pick one ion at this index, wrap it in brackets [].
Loading from PowerShell Exported Data...
color_map = 'FCC' not exists, falling back to default color map.
Loading from PowerShell Exported Data...

Initializing Figure

Tweaking `init_figure` by using `gridspec`.

This is a powerful way yo include any type of grid. For this, first use gs = axs[0,0].get_gridspec() and then remove axes you want to replace for another shape, then add required axis by plt.gcf().add_subplot(gs[x_ind, y_ind]). This process is illustrated in below examples.

Soft Tweaking
- Axes remain same, just widths and height ratios are chnaged.

import pivotpy.s_plots as sp 
axs = init_figure(figsize=(3.4,2.6),ncols=3,widths=[3.4,1,3.4],nrows=3,heights=[2.6,1,2.6],wspace=0.076,hspace=0.1)
[sp.modify_axes(ax=ax,xticks=[0],yticks=[0]) for ax in axs.ravel()]
[sp.add_colorbar(ax=ax,ticks=[]) for ax in [axs[1,0],axs[1,2]]];
_ = [sp.add_colorbar(ax=ax,vertical=True,ticks=[]) for ax in [axs[0,1],axs[2,1]]]

Brute Force Tweaking
- Here we will remove and regenerate axes based on our grid choice.

axs=init_figure(figsize=(5,3.4),nrows=3,ncols=2,widths=[1,1],heights=[1,7,7],wspace=0.4,hspace=0.4,axes_off=[(2,0)],sharex=True,sharey=True)
import pivotpy.s_plots as sp 
import matplotlib.pyplot as plt
gs = axs[0,0].get_gridspec()
axs_to_remove=[*axs[0, :],*axs[1:, 1]]
for ax in axs_to_remove:
    ax.remove()
axlarge = plt.gcf().add_subplot(gs[0, :])
axv = plt.gcf().add_subplot(gs[1:, 1])
sp.modify_axes(ax=axv)
sp.add_colorbar(ax=axlarge)
sp.add_text(ax=axs[1,0],txts='axis[1,0]',xs=0.25,ys=0.5)
sp.add_text(ax=axs[2,0],txts='axis[2,0] is off',xs=0.15,ys=0.5)
import pivotpy.vr_parser as vp 
vr=vp.export_vasprun(path='E:/Research/graphene_example/ISPIN_1/bands/vasprun.xml')
sp.quick_bplot(path_evr=vr,ax=axv,txt='Plotting',E_Fermi=10)
sp.add_text(ax=axv,txts='BigAxes',xs=0.25,ys=0.5)

Mixing 2D and 3D axes in a figure
- A minial example below shows deleting an axes and then adding a 3D axes with same dimensions.

from mpl_toolkits.mplot3d import Axes3D
import matplotlib.pyplot as plt 
import pivotpy as pp 
ax = pp.init_figure(nrows=2,ncols=2,widths=[1,2],heights=[1,2])
pos = ax[1,1].get_position()
ax[1,1].remove()
ax[1,1]=plt.gcf().add_axes(pos,projection='3d')

Plotting Density of States

Providing labels while using collect_dos is important, it will automatically return spin up/down saymbols.

quick_dos_lines(path_evr='E:/Research/graphene_example/ISPIN_2/dos/vasprun.xml',vertical=False,fill_area=True,showlegend=True,include_dos='pdos',orbs=[[1,2,3],0,1],elements=[0,0,1],linewidth=1,labels=['p','s','g'],color_map='RGB',elim=[-5,5],spin='both')

<matplotlib.axes._subplots.AxesSubplot at 0x1d441494ec8>

High Display Image in Notebook

The function below plt_to_html is implemented for use in pivotpy-dash app to view and save SVG image directly from web app's interface. This also enables high display output in jupyter notebook.

import pivotpy as pp 
import matplotlib.pyplot as plt
pp.quick_bplot("E:/Research/graphene_example/ISPIN_1/bands/vasprun.xml",elim=[-9,9]);
fig = plt_to_html(dash_html=None,transparent=False)
fig

Below code snippest could be used to inclue svg in html document from a figure.

data = plt_to_html(dash_html=False)
html_str= """
<!DOCTYPE html>
<head></head>
<body>
    <div>
    {}
    </div>
</body>
""".format(data)

with open('fig.html','w') as f:
    f.write(html_str)
f.close()

Passing Large Number of Arguments as a Dictionary

Simple Band Struture Plots

`plot_bands`[source]

`modify_axes`[source]

Example: Graphene

`quick_bplot`[source]

`add_text`[source]

`add_legend`[source]

`add_colorbar`[source]

`color_wheel`[source]

Including Atomic and Orbital Projections

`get_pros_data`[source]

`make_line_collection`[source]

`plot_collection`[source]

`quick_rgb_lines`[source]

`quick_color_lines`[source]

Colors Selection

Initializing Figure

`init_figure`[source]

Tweaking `init_figure` by using `gridspec`.

Plotting Density of States

`select_pdos`[source]

`collect_dos`[source]

`quick_dos_lines`[source]

High Display Image in Notebook

`plt_to_html`[source]

LOCPOT/CHG Plot

`plot_potential`[source]

Passing Large Number of Arguments as a Dictionary

Simple Band Struture Plots

plot_bands[source]

modify_axes[source]

Example: Graphene

quick_bplot[source]

add_text[source]

add_legend[source]

add_colorbar[source]

color_wheel[source]

Including Atomic and Orbital Projections

get_pros_data[source]

make_line_collection[source]

plot_collection[source]

quick_rgb_lines[source]

quick_color_lines[source]

Colors Selection

Initializing Figure

init_figure[source]

Tweaking init_figure by using gridspec.

Plotting Density of States

select_pdos[source]

collect_dos[source]

quick_dos_lines[source]

High Display Image in Notebook

plt_to_html[source]

LOCPOT/CHG Plot

plot_potential[source]

`plot_bands`[source]

`modify_axes`[source]

`quick_bplot`[source]

`add_text`[source]

`add_legend`[source]

`add_colorbar`[source]

`color_wheel`[source]

`get_pros_data`[source]

`make_line_collection`[source]

`plot_collection`[source]

`quick_rgb_lines`[source]

`quick_color_lines`[source]

`init_figure`[source]

Tweaking `init_figure` by using `gridspec`.

`select_pdos`[source]

`collect_dos`[source]

`quick_dos_lines`[source]

`plt_to_html`[source]

`plot_potential`[source]